Instructions for the ide example DELIVER.IDE.
//
// Instructions for Deliver.ide
// Copyright Borland International, 1993
//

PLEASE read this entire explanation before venturing off to use the
Deliver utilities. It is important to understand this program reads and
*writes* to your disk so be careful.

Deliver and Deliverd are tools for basic file manipulation during the
making of a project. They are called Deliver because their main purpose
is intended to be used as moving project targets (.exe,.lib, etc.) from
an intermediate area to a final 'delivery' area, however having the
source code to these programs allows you to extend and enhance their
functionality. It can be used as 'Tool' menu item to do general house-
cleaning.

The Deliver.exe is the Windows16 version of the program. It will run
fast but does not provide feedback of what's it's doing and being a
Windows app its 'return code' cannot be used to stop a build. The
Deliverd.exe is the DOS16 version and can be used in make file scripts
or in the IDE in conjunction with the $CAP MSG(BORL2MSG) filter to pump 
status but it will run slower since it has to invoke a 'DOS box' to run. 
Also, because it is a DOS app, its return code can be used to stop 
a build in progress in case of mishap.

Deliver currently recognizes the following commands:

COPY	 <source> [<source> ...] <destination>
MOVE   <source> [<source> ...] <destination>
MKDIR  <newdir> [<newdir> ...]
CLEAN  <filespec> [<filespec> ... ]
RENAME <oldname> <newname>

Of these commands COPY, MOVE, and CLEAN take wildcards in the first
argument(s).

Any piece of a command line (including the command) can be placed into
a response file. The response file name must be preceded with the '+'
(plus) character. For example:

	deliverd move +mydeps.rsp c:\deliver

Where mydeps.rsp contains "c:\myproj\libs\*.lib c:\myproj\final\*.dll".

NOTE: Do not think that because some command names correspond to DOS
commands with similar names and functionality, that they perform the
same way. In many cases they do, but in many cases they do not (e.g.
the RENAME command does not handle wildcards).


USING DELIVERW/D IN THE IDE:
------------------------------

Deliver/d tools can be used in one of several ways:
	1. Create a 'generic' utility to be used from the 'Tool' menu
		that prompts for command line
	2. Create a tool for every general combination you use it for
	3.	Create one tool and use the 'Command line options' local
		override field of every node you apply to tool to
	4. Some combination of 2 and 3

To install Deliver in the 1. case, do the following:
	Select Options|Tools from the main menu.
	Add a NEW tool and fill in the fields as follows:
	  Name:      HouseCleaner
	  Path:      deliver.exe
	  Command:   $PROMPT
	  Menu:      &File utility
	  Help Hint: General house cleaning tool
	  OK, Close
	
For examples of number 2. see examples\windows\makeall.ide for Deliver's 
use on the targets chelp, deliver, and helpex.

We will proceed assuming number 3. above since it is the most involved,
however you will most likely experiment until you find the right balance
for your projects. In any event, Deliver is most useful when attached 
to a SourcePool nodes (but even that is not strict policy).

First you must add one (or both) of the Deliver .exe's as a tool:

	Select Options|Tools from the main menu.
	Add a NEW tool and fill in the fields as follows:
	  Name:      Deliver
	  Path:      deliver.exe
	  Command: 
	  Menu:      &Deliver
	  Help Hint: Node's file deliver utility

	Select the Advanced button:
	  check   Translator,
	  check   Place on SpeedMenu,
	  uncheck Place on Tools menu
	  Translate from: SourcePool;
							(Spelling counts, so does case!!)
	OK, OK, Close.

Now you are ready to apply the tool to a node in your project:

	Select Project|New Target
	Fill in the 'Target name:' field
	Select 'Source Pool' from the 'Target type' dropdown
	OK (this will create a new [SourcePool] node in your project)
	Select 'Edit node attributes' from the node's SpeedMenu 
	Select 'Deliver' from the 'Translators:' dropdown
	OK
	Select 'Edit local options' from the node's SpeedMenu
	Select 'Tool' from the 'Topics list'
	Enter the deliver command line in the 'Command line options' field
	OK

NOTE: If you are using deliverd.exe, you will want to precede all 
local command lines with:
	$NOSWAP $CAP MSG(BOR2MSG.DLL)

	
EXAMPLES:
----------

1.	To deliver an [.hlp] target to delivery area "Q:\PRODUCT":
	  Add a SourcePool called "q:\product\myproj.hlp" with this local 
	  command line:
		 COPY  $NAME($EDNAME)$EXT($EDNAME) $DRIVE($EDNAME)$DIR($EDNAME)

	  This will expand to:
		 COPY myproj.hlp q:\product\

	  and will copy myproj.hlp from the current directory to q:\product.
		 
2. To make a tree of directories for a project:
		Add a SourcePool called "Tree Maker" with this local command line:
		  MKDIR OBJS OBJS\S OBJS\M OBJS\L OBJS\H

3. To clean the tree of directories for a project:
		Add a SourcePool called "Tree Cleaner" with this local command line:
		  CLEAN OBJS\S\*.* OBJS\M\*.* OBJS\L\*.* OBJS\H\*.*

4. To copy sources to a safe area after an edit session:
		Add a SourcePool called "Copy to safe"
		Move all sources nodes you wish to copy under "Copy to safe"
		Reference copy "Copy to safe" back to the target
		On the original (bold) "Copy to safe" make 'Deliver' its
		translator and put this local command line:
			COPY +$RSP($DEPLIST) c:\safe\haven
		
		
TIPS AND CAVEATS
-----------------

1. REMEMBER: This tool deletes and copies over files on disk.

2. Do *not* experiment with this tool on projects you like. Make 
	sure that a given piece of functionality you are trying to test 
	works and works well in a testbed situation.

3. If you are not sure what a given set of transfer macros will expand 
	out to be, place a $PROMPT at the beginning of the command line and
	run the tool. In the prompt box you get a preview of the command 
	line that would be passed to the tool. You should *CANCEL* from 
	this box if you have doubts about its validity.

4. If you find yourself typing in the same local command more than a few
	times, consider copying the original 'Deliver' tool. You do this 
	by:
		Select Options|Tools from the main menu
		Select 'DeliverWin'
		Push 'Copy' button
		Change the name
		Enter a command line
		Change the menu text
		OK, DONE 
	
5.	There is no law that says this tool can only apply to [SourcePool]
	node types, you apply the tool to .exe, .dll, AppExpert etc. by:
		Select Options|Tools from the main menu
		Select 'DeliverWin'
		Push 'Edit' button
		Push 'Advanced' button
		In 'Translate from' field add ".exe;.dll" to what's there
		OK, OK, DONE